How does this readme related to the one in the WidgetManagment folder?

The readme.md file in the Contoso.Widget folder is the union of the content in each service name folder's readme.md file. This union file is required by RPSaaS. I just learned yesterday that they will get rid of the need for this file "someday".

Should it be an import of the other files instead of a copy of the content?

Also, I suspect there may be other tools that require the readme at this level as well.

I don't think the RPaaS schema validator will work if the top-level readme file imports (references) the lower-level readme files. I don't think other tools need this top-level readme because I had one team remove it entirely (because I didn't know about the RPaaS schema validation checker) and the schema validation checker was the only thing that broke.

I also know that docs & SDKs will refer to the lower-level readmes and not the top-level readme.

Or is splitting (and re-merging) the readmes the entire point of folder structure v2? For example, this spec already has two levels of folders under resource-manager, but only a single readme.md directly under resource-manager.

https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager

So, while this spec already has their swaggers using the v2 folder structure, their readme.md is still using the v1 structure? Is this why this spec works with "schema validation" today, but requires an extra (merged) readme after the readmes are split and moved down into sub-folders?

The high priority goal is to make each service self-contained.
So, each service has its own folder and ALL things related to this service are in that folder: tsp files, preview/stable swaggers, readme.md files, etc. And from these files, docs & SDKs are produced. If a service is later retired, then we can just delete the service folder and everything related to that service is deleted in one fell swoop.

For control-plane services, they are under an extra folder: the RP namespace folder (eg: Microsoft.Compute). data-plane doesn't have this extra folder. And, control-plane services all need this extra readme.md file because of RPaaS schema validation which validates all operations within the RP namespace regardless of how the operations are split across multiple services. The RPaaS team told me that they hope to get rid of the requirement for this extra readme.md file in the future so this is required as a stop gap until then.

Got it, so it's what I said in my last paragraph. Some specs already in main split their swaggers into self-contained folders, but they still use a single readme.md at the top-level of resource-manager.

For these specs (like compute), the only change in v2 will be splitting the existing readme.md into multiple files, one per "service", and one extra readme per "RP namespace" (hopefully temporary).

Will all the content need to be duplicated in those split readmes? Or only part of the info? We need to figure out what is needed in each type of readme to ensure the duplication and confusion is minimal.

Each service readme.md has only what's needed for that specific service. The readme inside the RP namespace folder is the union of the other service readme files. The service readme should only have paths in it to swagger files in the same service and to nothing outside of that service.